/******************************************************************************
 * Copyright (C) 2025 FILEXSPACE, Inc.(Gmbh) or its affiliates.
 * 
 * All Rights Reserved.
 * 
 * @file bsp_led_driver.h
 * 
 * @par dependencies 
 * - bsp_led_driver.h
 * - stdio.h
 * - stdint.h
 * 
 * @author FANS | R&D Dept. | FILEXSPACE FILEX?????
 * 
 * @brief Provide the HAL APIs of LED and corresponding opetions.
 * 
 * Processing flow:
 * 
 * call directly.
 * 
 * @version V1.0 2025-02-27
 *
 * @note 1 tab == 4 spaces!
 * 
 *****************************************************************************/
#ifndef __BSP_LED_DRIVER_H
#define __BSP_LED_DRIVER_H

//******************************** Includes *********************************//

#include <stdint.h>              
#include <stdio.h>

//******************************** Includes *********************************//

//******************************** Defines **********************************//
#define INITED            0     /* LED is inited                             */
#define DEINITED          0     /* LED is not inited                         */

#define DEBUG                   /* Enable DBG                                */
#define DEBUG_OUT(X)      printf(X)        

#define OS_SUPPORTING         /* OS_SUPPORTING depending on OS avaliable   */

typedef enum
{
    LED_OK              = 0,    /* LED Operation completed successfully.     */
    LED_ERROR           = 1,    /* LED Run-time error without case matched.  */
    LED_ERROR_TIMEOUT   = 2,    /* LED Operation failed with timeout.        */
    LED_ERROR_RESOURCE  = 3,    /* LED Resource not available.               */
    LED_ERROR_PARAMETER  = 4,    /* LED Parameter error.                      */
    LED_ERROR_MEMORY    = 5,    /* LED Out of memory.                        */
    LED_ERROR_ISR       = 6,    /* LED Not allowed in ISR context.           */
    LED_RESERVED        = 0xff, /* LED Reserved*/
}led_status_t;

typedef enum
{
    PROPORTION_1_3 = 0,         /* LED Operation completed successfully.     */
    PROPORTION_1_2 = 1,         /* LED Operation completed successfully.     */
    PROPORTION_1_1 = 2,         /* LED Operation completed successfully.     */
    PROPORTION_x_x = 0xff,      /* LED Operation completed successfully.     */
}proportion_t;

typedef struct
{
    led_status_t (*pf_led_on) (void); /*LED Operation completed successfully.     */
    led_status_t (*pf_led_off)(void); /*LED Operation completed successfully.     */
}led_operations_t;

typedef struct
{
    led_status_t (*pf_get_time_ms) ( uint32_t * const ); /* data */
}time_base_t;

#ifdef OS_SUPPORTING
/**
 * @brief 定义一个结构体类型os_delay_t，用于操作系统延迟函数的抽象
 * 
 * 该结构体包含一个函数指针成员，指向一个特定形式的函数该函数用于实现毫秒级的延迟
 * 在嵌入式系统或需要精确控制执行时间的应用程序中，这种延迟函数非常有用
 */
typedef struct
{
    led_status_t (*pf_os_delay_ms) ( const uint32_t ); /* data */
}os_delay_t;
#endif /*OS_SUPPORTING*/

typedef led_status_t (*pf_led_control_t)(
                                         uint32_t ,       //cycle
                                         uint32_t ,       //times
                                         proportion_t     //proportion
                                                     );

typedef struct
{
    /************************** 内部状态 **********************************/
    uint8_t                       is_inited; /* 初始化状态 */

    /*****************Target Features**************/
    /*blink cycle */
    uint32_t                 blink_cycle_ms;
    /*blink times */
    uint32_t                    blink_times;
    /*proportion of light on and off time*/
    proportion_t          proportion_on_off;

    /********************Target IO*****************/
    /*Interface from Core Layer*/
    led_operations_t       *p_led_opes_inst;
    time_base_t             *p_time_base_ms;
#ifdef OS_SUPPORTING
    /*Interface from OS Layer*/
    os_delay_t             *p_os_time_delay;
#endif //OS_SUPPORTING

    /************Target of External APIs***********/
    pf_led_control_t        *pf_led_control;

}bsp_led_driver_t;
//******************************** Defines **********************************//

//******************************* Declaring *********************************//
/** 
* @brief instantiate the target of
* 
* Steps:
* 1,XOR each byte of the input data with the CRC register.
* 2,For each bit,check the most significant bit.
* 3,Shift the CRC register left and,if the most significant bit is 1,
* XOR with the polynomial.
*
* @param[in]self      Pointer to the input data.
* @param[in]led_ops   Length of the input data.
* @param[in]os_delay  Pointer to the input data.
* @param[in]time_base Pointer to the input data.
* 
* @return led_status_t : The calculated CRC-8 checksum.
**/
led_status_t led_driver_inst(
                                      bsp_led_driver_t * const self,  //定义一个obj
                                const led_operations_t * const led_ops,
#ifdef OS_SUPPORTING
                                const os_delay_t       * const os_delay,
#endif //OS_SUPPORTING
                                const time_base_t      * const time_base         
);
//******************************* Declaring *********************************//


#endif  /*__BSP_LED_DRIVER_H*/
